4. XSL Extension Controls

All XSL controls operate on the XSL context node (“.”) by default. Many Sitecore XSL extension controls accept a select attribute, which can reference an existing variable or parameter defining a Sitecore item, or an XPath statement that defines a Sitecore item. When the select attribute is used, the control will operate on that item rather than the XSL context node. If select is not specified, the context node is assumed (equivalent to select=".").

In addition to the select attribute, Sitecore XSL Extension controls which operate on the value of a field always require the field attribute specify the name of the field to process.

Examples of some functions described below are provided in sample.xslt distributed with the sample site.

4.1. Content Marker – <sc:dot>

If the CMS user is working in WebEdit or Preview mode, this control outputs a content marker to the Sitecore item defined by the current XSL context node or the item specified by the select attribute. The syntax of this control is:

<sc:dot [select="{item}"] />

The most common examples of using this control output a content marker to the current item and to it’s parent:

<sc:dot [select="$sc_currentitem"] />

<sc:dot [select="$sc_currentitem/.."] />

4.2. Date Field - <sc:date>

The xsl syntax of this control is:

<sc:date field="df" format="dd MMMM yyyy" />

This control outputs the value of a date field. The section 'dd MMMM yyyy' is customizable to a format that suits your application.

4.3. HTML Field - <sc:html>

The syntax of this control is:

<sc:html field="name" [select="item"] />

This control is intended to retrieve the value of the named HTML field in the current or specified item. This is basically equivalent to xsl:copy-of (a deep copy of the field with output escaping disabled).

The most common example of using this control retrieves the HTML of the Text field from the current record:

<sc:html select="$sc_currentitem" field="text" />

4.4. Image Field - <sc:image>

Note that this control is commonly mistyped as <sc:img ...>, which renders a literal <sc:img ...> to the output stream instead of generating an HTML <img> tag. The syntax of this control is:

<sc:image field="name" [select="item"] />

This control generates an HTML <img> tag referencing the image specified in the named field of type image in the current record or specified record. The most common example of this control generates HTML for an image from a field in the current record (Graphic is the field name in this example):

<sc:image field="graphic" select="$sc_currentitem" />

Note that it is not possible to pass custom arbitrary HTML attributes such as onclick. This can be resolved using XSL extension functions:

<img src="{sc:fld( 'graphic', $sc_currentitem, 'src’ )}”

onclick="function()" />

4.5. Link Field - <sc:link>

This control may have the greatest number of uses. The format is as follows:

<sc:link [field="field"] [text="title"] [select="item"] [attribute="value"...] />

An alternative syntax is:

<sc:link [field="field"] [select="item"] [attribute="value"...]>title</sc:link>

The difference is that the title of the link (what the user will see) appears between opening and closing tags instead of as an attribute of a self-closing tag. This is especially helpful for generating image links. If both are used, the attribute will override the element value. Title should always be specified unless field is specified, otherwise the <a> tag will be output but there will be nothing to click.

If field and select are not specified specified, a link (<a>) is generated to the current XSL context node. If field is not specified but select is specified, a link is generated to the specified node. If select is not specified but field is specified, a link is generated to the value of that field of type link in the XSL context node. If field and select are specified, a link is generated to the value of that field of type link in the specified Sitecore item.

This the only Sitecore control which supports overriding parameters (custom attributes will override link values in the specified field) and arbitrary parameters (class, onmouseover and other attributes will be passed directly through to the output).

As the only xsl control (for the moment), the sc:link field supports attribute overriding. That means that auto-generated values can be overridden if some other value is desired.

A common example of using sc:link is to generate a list of child documents:

<xsl:for-each select="$sc_currentitem/item">
<sc:link text="{@name}"/>
</xsl:for-each>

An example of an image link is as follows:

<sc:link field="link"><sc:image field="linkgraphic"/></sc:link>

4.6. Restrict Access - <sc:sec>

The syntax of this element is as follows:

<sc:sec [require="right"] [select="item"]>{restricted code}</sc:sec>

The block of code within the <sc:sec> element will only be executed if the current user has the specified right on the context node or specified item. The value of the require attribute can be any of the Sitecore Permission Codes except “o” (None).

An example of using this control is as follows:

<sc:sec require="r">

<sc:html field="text"/>

</sc:sec>

A more common implementation branches based on whether the user is authenticated and has permission (using xsl:choose, sc: IsLoggedIn, sc:IsRestricted and sc:HasRight):

<xsl:choose>

<xsl:when test="not( sc:IsRestricted( . )) or ( sc:IsLoggedIn() and sc:HasRight( 'r', . ))">

<sc:html field="text">

</xsl:when>

<xsl:when test="sc:IsLoggedIn()">

</xsl:when>

<xsl:otherwise>

</xsl:otherwise>

</xsl:choose>

4.7. Field Value - <sc:text>

The syntax of this control is:

<sc:text field="name" [select=" item"] />

This control simply outputs the entire value of the specified field with output escaping enabled. A common example outputs the value of the text field Title:

<sc:text field="title" select="$sc_currentitem" />

Prev Next